Skip Headers

Oracle® Database Data Cartridge Developer's Guide, 10g Release 2 (10.2) Part Number B14289-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 20 Extensible Indexing Interface

This chapter describes Java language Oracle Data Cartridge Interface extensible indexing interfaces. This chapter contains this topic:

- Extensible Indexing - System-Defined Interface Routines

See Also: Oracle Data Cartridge Java API Reference

## Extensible Indexing - System-Defined Interface Routines

These routines are invoked by Oracle at the appropriate times based on SQL statements executed by the end user.

Caution: Do not invoke these routines directly as this may result in corruption of index data.

Table 20-1 summarizes the extensible indexing routines.

Table 20-1 Summary of System-Defined Extensible Indexing Interface Routines

Routine | Description
--- | ---
ODCIGetInterfaces() | Invoked when an `INDEXTYPE` is created by a `CREATE` `INDEXTYPE...` statement or is altered.
ODCIIndexAlter() | Invoked when a domain index or a domain index partition is altered using an `ALTER INDEX` or an `ALTER INDEX PARTITION` statement.
ODCIIndexClose() | Invoked to end the processing of an operator.
ODCIIndexCreate() | Invoked when a domain index is created by a `CREATE INDEX...INDEXTYPE IS...PARAMETERS...` statement issued by the user.
ODCIIndexDelete() | Invoked when a row is deleted from a table that has a domain index defined on one or more of its columns.
ODCIIndexDrop() | Invoked when a domain index is dropped explicitly using a `DROP` `INDEX` statement, or implicitly through a `DROP` `TABLE` or `DROP` `USER` statement.
ODCIIndexExchangePartition() | Invoked when an `ALTER TABLE EXCHANGE PARTITION...INCLUDING INDEXES` is issued on a partitioned table which has a local defined domain index.
ODCIIndexFetch() | Retrieves the rows satisfying the operator predicate.
ODCIIndexGetMetadata() | Returns a series of strings of PL/SQL code that comprise the non-dictionary metadata associated with the index.
ODCIIndexInsert() | Invoked when a row or a set of rows is inserted into a table that has a defined domain index on one or more of its columns.
ODCIIndexMergePartition() | Invoked when a `ALTER TABLE MERGE PARTITION` is issued on range partitioned table which has a local defined domain index.
ODCIIndexSplitPartition() | Invoked when an `ALTER TABLE SPLIT PARTITION` is invoked on a partitioned table which has a local defined domain index.
ODCIIndexStart() | Starts the evaluation of an operator on an indexed column.
ODCIIndexTruncate() | Invoked when a `TRUNCATE` statement is issued against a table that has a defined domain index on one of its columns.
ODCIIndexUpdate() | Invoked when a row is updated in a table and the updated column has a defined domain index
ODCIIndexUtilCleanup() | Cleans up any temporary state created by ODCIIndexUtilGetTableNames().
ODCIIndexUtilGetTableNames() | Determines if the secondary tables storing the index data should be transported.

### ODCIGetInterfaces()

The `ODCIGetInterfaces` function is invoked when an `INDEXTYPE` is created by a `CREATE` `INDEXTYPE...` statement or is altered.

Syntax

    ODCIGetInterfaces(
       ifclist OUT ODCIObjectList) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ifclist
    OUT
| Contains information about the interfaces it supports

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error

Usage Notes

- This function should be implemented as a static type method.

- This function must return `SYS.ODCIINDEX2` in the `ODCIObjectList` if the indextype uses the second version of the `ODCIIndex` interface, which was implemented in the current version of the Oracle Database and is described in this book.

- To continue to use the Oracle8i interface, make this function return `SYS.ODCIINDEX1` and do not implement subsequent versions of the routines.

### ODCIIndexAlter()

Invoked when a domain index or a domain index partition is altered using an `ALTER INDEX` or an `ALTER INDEX PARTITION` statement.

Syntax

    ODCIIndexAlter(
       ia ODCIIndexInfo,
       parms IN OUT VARCHAR2,
       alter_option NUMBER,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the index and the indexed column
    parms
    IN
| Parameter string With `ALTER` `INDEX` `PARAMETERS` or `ALTER` `INDEX` `REBUILD`, contains the user specified parameter string With `ALTER` `INDEX` `RENAME`, contains the new name of the domain index
    parms
    OUT
| Parameter string Valid only with `ALTER` `INDEX` `PARAMETERS` or `ALTER` `INDEX` `REBUILD`; Contains the resultant string to be stored in system catalogs
    alter_option
|  | Specifies one of the following options: `AlterIndexNone` if `ALTER INDEX [PARTITION] PARAMETERS` `AlterIndexRename` if `ALTER INDEX RENAME [PARTITION]` `AlterIndexRebuild` if `ALTER INDEX REBUILD [PARTITION] [PARALLEL (DEGREE deg)] [PARAMETERS]` `AlterIndexUpdBlockRefs` if `ALTER INDEX [schema.]index UPDATE BLOCK REFERENCES`
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, `ODCIConst.Error` on error, or `ODCIConst.Warning` otherwise.

Usage Notes

- This function should be implemented as a static type method.

- An `ALTER` `INDEX` statement can be invoked for domain indexes in multiple ways.

      ALTER INDEX index_name
      PARAMETERS (parms);

  or

      ALTER INDEX index_name
      REBUILD PARAMETERS (parms);

  The precise behavior in these two cases is defined by the implementor. One possibility is that the first statement would merely reorganize the index based on the parameters while the second would rebuild it from scratch.

- The maximum length of the input parameters string is 1000 characters. The `OUT` value of the `parms` argument can be set to resultant parameters string to be stored in the system catalogs.

- The `ALTER` `INDEX` statement can also be used to rename a domain index in the following way:

      ALTER INDEX index_name
      RENAME TO new_index_name

  In this case, the new name of the domain index is passed to the `parms` argument.

- If the `PARALLEL` clause is omitted, then the domain index or local domain index partition is rebuilt sequentially.

- If the `PARALLEL` clause is specified, the parallel degree is passed to the `ODCIIndexAlter` invocation in the `IndexParaDegree` attribute of `ODCIIndexInfo`, and the `Parallel` bit of the `IndexInfoFlags` attribute is set. The parallel degree is determined as follows:

  - If `PARALLEL DEGREE` deg is specified, deg is passed.

  - If only `PARALLEL` is specified, then a constant is passed to indicate that the default degree of parallelism was specified.

- If the `ODCIIndexAlter` routine returns with the `ODCIConst`.`Success`, the index is valid and usable. If the `ODCIIndexAlter` routine returns with `ODCIConst`.`Warning`, the index is valid and usable but a warning message is returned to the user. If `ODCIIndexAlter` returns with an error (or exception), the domain index will be marked `FAILED`.

- When the `ODCIIndexAlter` routine is being executed, the domain index is marked `LOADING`.

- Every SQL statement executed by ODCIIndexAlter is treated as an independent operation. The changes made by ODCIIndexCreate are not guaranteed to be atomic.

- The `AlterIndexUpdBlockRefs` alter option applies only to domain indexes on index-organized tables. When the end user executes an `ALTER INDEX` <domain_index> `UPDATE BLOCK REFERENCES`, `ODCIIndexAlter` is called with the `AlterIndexUpdBlockRefs` bit set to give the cartridge developer the opportunity to update guesses as to the block locations of rows, stored in logical rowids.

### ODCIIndexClose()

Invoked to end the processing of an operator.

Syntax

    ODCIIndexClose(
       self IN <impltype>,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    self(IN)
    IN
| Is the value of the context returned by the previous invocation of `ODCIIndexFetch`
    env
| The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, `ODCIConst.Error` on error

Usage Notes

- The index implementor can perform any appropriate actions to finish up the processing of an domain index scan, such as freeing memory and other resources.

### ODCIIndexCreate()

Invoked when a domain index is created by a `CREATE INDEX...INDEXTYPE IS...PARAMETERS...` statement issued by the user. The domain index that is created can be a non-partitioned index or a local partitioned domain index.

Syntax

    ODCIIndexCreate(
       ia ODCIIndexInfo,
       parms VARCHAR2,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the indexed column
    parms
| Is the `PARAMETERS` string passed in uninterpreted by Oracle. The maximum size of the parameter string is 1000 characters.
    env
|  | The environment handle passed to the routine

Returns

- `ODCIConst.Success` on success

- `ODCIConst.Error` on error

- `ODCIConst.Warning`

- `ODCIConst.ErrContinue` if the method is invoked at the partition level for creation of a local partitioned index, to continue to the next partition even in case of an error

- `ODCIConst.Fatal` to signify that all dictionary entries for the index are cleaned up and that the `CREATE INDEX` operation is rolled back. Returning this status code assumes that the cartridge code has not created any objects (or cleaned up any objects created).

Usage Notes

- This function should be implemented as a static type method.

- The `ODCIIndexCreate` routine should create objects (such as tables) to store the index data, generate the index data, and store the data in the index data tables.

- The `ODCIIndexCreate` procedure should handle creation of indexes on both empty and non-empty tables. If the base table is not empty, the `ODCIIndexCreate` procedure can scan the entire table and generate index data.

- Every SQL statement executed by `ODCIIndexCreate` is treated as an independent operation. The changes made by `ODCIIndexCreate` are not guaranteed to be atomic.

- For a non-partitioned domain index, the parallel degree is passed to the `ODCIIndexCreate` invocation in the `IndexParaDegree` attribute of `ODCIIndexInfo`, and the `Parallel` bit of the `IndexInfoFlags` is set. The parallel degree is determined as follows:

  - If `PARALLEL DEGREE` deg specified, deg is passed.

  - If only `PARALLEL` is specified, then a constant indicating that the default degree of parallelism was specified, is passed.

  - If the `PARALLEL` clause is omitted altogether, the operation is done sequentially

- When the `ODCIIndexCreate` routine is being executed, the domain index is marked `LOADING`.

- If the `ODCIIndexCreate` routine returns with the `ODCIConst`.`Success`, the index is valid and usable. If the `ODCIIndexCreate` routine returns with `ODCIConst`.`Warning`, the index is valid and usable but a warning message is returned to the user. If the `ODCIIndexCreate` routine returns with an `ODCIConst`.`Error` (or exception), the domain index will be marked `FAILED.`

- The only operations permitted on `FAILED` domain indexes is `DROP` `INDEX`, `TRUNCATE` `TABLE` or `ALTER` `INDEX` `REBUILD`.

- If a domain index is created on an column of object type which contains a `REF` attribute, do not dereference the `REF`s while building your index. Dereferencing a `REF` fetches data from a different table instance. If the data in the other table is modified, you will not be notified and your domain index will become incorrect.

- To create a non-partitioned domain index, the `ODCIIndexCreate` method is invoked once, and the only valid return codes are `ODCIConstSuccess`, `ODCIConstWarning` or `ODCIConstError`. The `IndexPartition` and `TablePartition` name are `NULL` and `callProperty` is also `NULL`.

- To create a local partitioned domain index, the `ODCIIndexCreate` method is invoked n`+2` times, where n is the number of local index partitions. The first and the final call handle operations on the top-level index object, and the intermediate n calls handle partition-level objects. In the first call, a table to hold the index level metadata can be created. In the intermediate calls, independent tables to hold partition level data can be created and populated, and in the last call, indexes can be built on the index metadata tables and so forth.

- For local partitioned domain indexes, the first and the last call can return `ODCIConstSuccess`, `ODCIConstWarning` or `ODCIConstError`. The intermediate N calls can return `ODCIConstSuccess`, `ODCIConstWarning`, `ODCIConstError` or `ODCIConstErrContiue`. If a partition level call returns `ODCIConstError`, the partition is marked `FAILED`, the index is marked `FAILED`, and the create operation terminates at that point. If the call returns `ODCIConstErrContinue`, the partition is marked `FAILED`, and the method is invoked for the next partition.

- This method is invoked during `ALTER TABLE ADD PARTITION` too. In this case, there is only one call to `ODCIIndexCreate`, the `IndexPartition` and `TablePartition` name are filled in, and the `callProperty` is set to `NULL`

- Since this routine handles multiple things (namely, creation of a non-partitioned index, creation of a local index and creation of a single index partition), you must take special care to code it appropriately.

### ODCIIndexDelete()

Invoked when a row is deleted from a table that has a domain index defined on one or more of its columns.

Syntax

    ODCIIndexDelete(
       ia ODCIIndexInfo,
       rid VARCHAR2,
       oldval <icoltype>,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the index and the indexed column
    rid
| The row identifier of the deleted row
    oldval
|  | The value of the indexed column in the deleted row. The datatype is the same as that of the indexed column.
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error

Usage Notes

- This function should be implemented as a static type method.

- This method should delete index data corresponding to the deleted row from the appropriate tables or files storing index data.

- If `ODCIIndexDelete` is invoked at the partition level, then the index partition name is filled in the `ODCIIndexInfo` argument.

### ODCIIndexDrop()

The `ODCIIndexDrop` procedure is invoked when a domain index is dropped explicitly using a `DROP` `INDEX` statement, or implicitly through a `DROP` `TABLE` or `DROP` `USER` statement.

Syntax

    ODCIIndexDrop(
       ia ODCIIndexInfo,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the indexed column
    env
| The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error, or `ODCIConst.Warning`

While dropping a local domain index, the first n`+1` calls can return `ODCIConst.ErrContinue` too.

Usage Notes

- This method should be implemented as a static type method.

- This method should drop the tables storing the domain index data.

- This method is invoked for dropping a non-partitioned index, dropping a local domain index, and also for dropping a single index partition during `ALTER TABLE DROP PARTITION`.

  For dropping a non-partitioned index, the `ODCIIndexDrop` is invoked once, with the `IndexPartition`, `TablePartition` and `callProperty` set to `NULL`.

  For dropping a local domain index, the routine is invoked N+2 times, where N is the number of partitions.

  For dropping a single index partition during `ALTER TABLE DROP PARTITION`, this routine is invoked once with the `IndexPartition` and the `TablePartition` filled in and the `callProperty` set to `NULL`.

  The old table and the old index partition's dictionary entries are deleted before the call to `ODCIIndexDrop`, so the cartridge code for this routine should not rely on the existence of this data in the views.

- Since it is possible that the domain index is marked `FAILED` (due to abnormal termination of some DDL routine), the `ODCIIndexDrop` routine should be capable of cleaning up partially created domain indexes. When the `ODCIIndexDrop` routine is being executed, the domain index is marked `LOADING`.

- Note that if the `ODCIIndexDrop` routine returns with an `ODCIConst.Error` or exception, the `DROP` `INDEX` statement fails and the index is marked `FAILED`. In that case, there is no mechanism to get rid of the domain index except by using the `FORCE` option. If the `ODCIIndexDrop` routine returns with `ODCIConst`.`Warning` in the case of an explicit `DROP` `INDEX` statement, the operation succeeds but a warning message is returned to the user.

- Every SQL statement executed by `ODCIIndexDrop` is treated as an independent operation. The changes made by `ODCIIndexDrop` are not guaranteed to be atomic.

### ODCIIndexExchangePartition()

This method is invoked when an `ALTER TABLE EXCHANGE PARTITION...INCLUDING INDEXES` is issued on a partitioned table on which a local domain index is defined.

Syntax

    ODCIIndexExchangePartition(
       ia ODCIIndexInfo,
       ia1 ODCIIndexInfo,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
ia |
| Contains information about the partition to exchange
ia1 |
| Contains information about the non-local, unpartitioned domain index
env |  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error, or `ODCIConst.Warning`

Usage Notes

The function should be implemented as a static type method.

This method should handle both converting a partition of a domain index into a non-partitioned domain index table and converting a non-partitioned index to a partition of a partitioned domain index.

### ODCIIndexFetch()

This procedure is invoked repeatedly to retrieve the rows satisfying the operator predicate.

Syntax

    ODCIIndexFetch(
       self IN [OUT] <impltype>,
       nrows IN NUMBER,
       rids OUT ODCIRidList,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    self(IN)
    IN
| Is the value of the context returned by the previous call (to `ODCIIndexFetch` or to `ODCIIndexStart` if this is the first time fetch is being called for this operator instance
    self(OUT)
    OUT
| The context that is passed to the next query-time call. Note that this parameter does not have to be defined as `OUT` if the value is not modified in this routine.
    nrows
|  | Is the maximum number of result rows that can be returned to Oracle in this call
    rids
|  | Is the array of row identifiers for the result rows being returned by this call
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error

Usage Notes

- `ODCIIndexFetch` returns rows satisfying the operator predicate. That is, it returns the row identifiers of all the rows for which the operator return value falls within the specified bounds.

- Each call to `ODCIIndexFetch` can return a maximum of nrows number of rows. The value of nrows passed in is decided by Oracle based on some internal factors. However, the `ODCIIndexFetch` routine can return lesser than nrows number of rows. The row identifiers are returned through the output `rids` array. A `NULL` `ROWID` (as an element of the `rids` array) indicates that all satisfying rows have been returned.

  Assume that there are 3000 rows which satisfy the operator predicate, and that the value of `nrows` = 2000. The first invocation of `ODCIIndexFetch` can return the first 2000 rows. The second invocation can return a `rid` list consisting of the remaining 1000 rows followed by a `NULL` element. The `NULL` value in `rid` list indicates that all satisfying rows have now been returned.

- If the context value is changed within this call, the new value is passed in to subsequent query-time calls.

### ODCIIndexGetMetadata()

Returns a series of strings of PL/SQL code that comprise the non-dictionary metadata associated with the index in `ia`. The routine can pass whatever information is required at import time. For example, policy, version, preferences, and so on. This method is optional unless implementation-specific metadata is required.

Syntax

    ODCIIndexGetMetadata(
       ia IN ODCIIndexInfo,
       version IN VARCHAR2,
       new_block OUT PLS_INTEGER) RETURN VARCHAR2;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
    IN
| Specifies the index on which export is currently working.
    version
    IN
| Version of export making the call in the form `08.01.03.00.00`.
    new_block
    OUT
| Non-zero (`TRUE`): Returned string starts a new PL/SQL block. Export will terminate the current block (if any) with `END`; and open a new block with `BEGIN` before writing strings to the dump file. The routine is called again. `0` (`FALSE`): Returned string continues current block. Export writes only the returned string to the dump file then calls the routine again.

Developers of domain index implementation types in 8.1.3 must implement `ODCIIndexGetMetadata` even if only to indicate that no PL/SQL metadata exists or that the index is not participating in fast rebuild.

Returns

- A null-terminated string containing a piece of an opaque block of PL/SQL code

- A zero-length string indicates no more data; export stops calling the routine

Usage Notes

- This function should be implemented as a static type method.

- The routine will be called repeatedly until the return string length is 0. If an index has no metadata to be exported using PL/SQL, it should return an empty string upon first call.

- This routine can be used to build one or more blocks of anonymous PL/SQL code for execution by import. Each block returned will be invoked independently by import. That is, if a block fails for any reason at import time, subsequent blocks will still be invoked. Therefore any dependent code should be incorporated within a single block. The size of an individual block of PL/SQL code is limited only by the size of import's read buffer controlled by its `BUFFER` parameter.

- The execution of these PL/SQL blocks at import time will be considered part of the associated domain index's creation. Therefore, their execution will be dependent upon the successful import of the index's underlying base table and user's setting of import's `INDEXES=Y/N` parameter, as is the creation of the index.

- The routine should not pass back the `BEGIN`/`END` strings that open and close the individual blocks of PL/SQL code; export will add these to mark the individual units of execution.

- The parameter `version` is the version number of the currently executing export client. Since export and import can be used to downgrade a database to the previous functional point release, it also represents the minimum server version you can expect to find at import time; it may be higher, but never lower.

- The cartridge developer can use this information to determine what version of information should be written to the dump file. For example, assume the current server version is `08.02.00.00.00`, but the export version handed in is `08.01.04.00.00`. If a cartridge's metadata changed formats between 8.1 and 8.2, it would know to write the data to the dump file in 8.1 format anticipating an import into an 8.1.4 system. Server versions starting at 8.2 and higher will have to know how to convert 8.1 format metadata.

- The data contained within the strings handed back to export must be completely platform-independent. That is, they should contain no binary information that may reflect the endian nature of the export platform, which may be different from the import platform. Binary information may be passed as hex strings and converted through `RAWTOHEX` and `HEXTORAW`.

- The strings are translated from the export server to export client character set and are written to the dump file as such. At import time, they are translated from export client character set to import client character set, then from import client char set to import server character set when handed over the UPI interface.

- Specifying a specific target schema in the execution of any of the PL/SQL blocks should be avoided as it will most likely cause an error if you exercise import's `FROMUSER` -> `TOUSER` schema replication feature. For example, a procedure prototype such as:

      PROCEDURE AQ_CREATE ( schema IN VARCHAR2, que_name IN VARCHAR2) ...

  should be avoided since this will fail if you have remapped schema A to schema B on import. You can assume at import time that you are already connected to the target schema.

- Export dump files from a particular version must be importable into all future versions. This means that all PL/SQL routines invoked within the anonymous PL/SQL blocks written to the dump file must be supported for all time. You may wish to encode some version information to assist with detecting when conversion may be required.

- Export will be operating in a read-only transaction if its parameter `CONSISTENT=Y`. In this case, no writes are allowed from the export session. Therefore, this method must not write any database state.

- You can attempt to import the same dump file multiple times, especially when using import's `IGNORE=Y` parameter. Therefore, this method must produce PL/SQL code that is idempotent, or at least deterministic when executed multiple times.

- Case on database object names must be preserved; that is, objects named '`Foo`' and '`FOO`' are distinct objects. Database object names should be enclosed within double quotes ("") to preserve case.

Error Handling

Any unrecoverable error should raise an exception allowing it to propagate back to `get_domain_index_metadata` and thence back to export. This will cause export to terminate the creation of the current index's DDL in the dump file and to move on to the next index.

At import time, failure of the execution of any metadata PL/SQL block will cause the associated index not to be created under the assumption that the metadata creation is an integral part of the index creation.

### ODCIIndexInsert()

Invoked when a row or a set of rows is inserted into a table that has a domain index defined on one or more of its columns.

Function | Description
--- | ---
    ODCIIndexInsert(
       ia ODCIIndexInfo,
       rid VARCHAR2,
       newval <icoltype>,
       env ODCIEnv) RETURN NUMBER;
| Inserts a single row
    ODCIIndexInsert(
       ia ODCIIndexInfo,
       ridlist ODCIRidList,
       newvallist <varray of column type>,
       env ODCIEnv) RETURN NUMBER;
| inserts a set of rows

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the index and the indexed column
    rid
|  | The row identifier of the new row in the table
    newval
|  | The value of the indexed column in the inserted row
    ridlist
|  | A varray (maximum size 32767) containing the list of rowids for the rows being inserted into the base table
    newvallist
|  | A varray (maximum size 32767) containing the list of values being inserted into the indexed column in the base table; these entries have a one-to-one correspondence with the entries in `ridlist`
    env
| The environment handle passed to the routine
    ia
|  | Contains information about the index and the indexed column

Returns

`ODCIConst``.Success` on success, or `ODCIConst.Error` on error

Usage Notes

- This function should be implemented as a static type method.

- This method should insert index data corresponding to the row or set of rows passed in into the appropriate tables or files storing index data. A NULL value in `ridlist` indicates the end of the varray.

- If the indextype is defined `WITH ARRAY DML`, a batch of rows can be inserted into the table. In this case, `ODCIIndexInsert` is invoked using the second of the two syntax synopses. Otherwise, the single-row syntax is used.

- If `ODCIIndexInsert` is invoked at the partition level, then the index partition name is filled in the `ODCIIndexInfo` argument.

### ODCIIndexMergePartition()

Invoked when a `ALTER TABLE MERGE PARTITION` is issued on range partitioned table on which a local domain index is defined.

Syntax

    ODCIIndexMergePartition(
       ia ODCIIndexInfo,
       part_name1 ODCIPartInfo,
       part_name2 ODCIPartInfo,
       parms VARCHAR2,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains index and table partition name for one of the partitions to be merged
    part_name1
| Contains index and table partition name for the second partition to be merged
    part_name2
|  | Holds index and table partition name for the merged partition
    parms
|  | Contains the parameter string for the resultant merged partition, essentially the default parameter string associated with the index
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error, or `ODCIConst.Warning`.

Usage Notes

- The function should be implemented as a static type method.

- You should create a new table representing the resultant merged partition and populate it with data from the merged partitions. Then drop the tables corresponding to the merged index partitions. Also, the newly created partition should pick the default parameter string associated with the index level.

  The old table and the old index partitions' dictionary entries are deleted before the call to `ODCIIndexMergePartition`, so the cartridge code for this routine should not rely on the existence of this data in the views.

### ODCIIndexSplitPartition()

Invoked when an `ALTER TABLE SPLIT PARTITION` is invoked on a partitioned table on which a local domain index is defined.

Syntax

    ODCIIndexSplitPartition(
       ia ODCIIndexInfo,
       part_name1 ODCIPartInfo,
       part_name2 ODCIPartInfo,
       parms VARCHAR2,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains the information about the partition to be split
    part_name1
|  | Holds the index and table partition names for one of the new partitions
    part_name2
|  | Holds the index and table partition names for the other new partition
    parms
| Contains the parameter string for the new partitions; essentially, the parameter string associated with the index partition that is being split
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error, or `ODCIConst.Warning`.

Usage Notes

- The function should be implemented as a static type method.

- Cartridge writers need to drop the metadata corresponding to the partition that is split and create metadata for the two partitions that are created as a result of the split. The index data corresponding to these partitions need not be computed since the indexes are marked `UNUSABLE`. When the user issues `ALTER INDEX REBUILD PARTITION` to make the indexes usable, the indexes can be built.

- The old table and the old index partition's dictionary entries are deleted before the call to `ODCIIndexSplitPartition`, so the cartridge code for this routine should not rely on the existence of this data in the views.

### ODCIIndexStart()

Invoked to start the evaluation of an operator on an indexed column.

Syntax

    ODCIIndexStart(
       sctx IN OUT <impltype>,
       ia ODCIIndexInfo,
       pi ODCIPredInfo,
       qi ODCIQueryInfo,
       strt <opbndtype>,
       stop <opbndtype>,
       <valargs>,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    sctx
    IN
| The value of the scan context returned by some previous related query-time call (such as the corresponding ancillary operator, if invoked before the primary operator); `NULL` otherwise
    sctx
    OUT
| The context that is passed to the next query-time call; the next query-time call will be to `ODCIIndexFetch`
    ia
|  | Contains information about the index and the indexed column
    pi
|  | Contains information about the operator predicate
    qi
|  | Contains query information (hints plus list of ancillary operators referenced)
    strt
|  | The start value of the bounds on the operator return value. The datatype is the same as that of the operator's return value
    stop
|  | The stop value of the bounds on the operator return value. The datatype is the same as that of the operator's return value.
    valargs
|  | The value arguments of the operator invocation. The number and datatypes of these arguments are the same as those of the value arguments to the operator.
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst``.Success` on success, or `ODCIConst.Error` on error

Usage Notes

- The function should be implemented as a static method.

- `ODCIIndexStart` is invoked to begin the evaluation of an operator on an indexed column. In particular, the following conditions hold:

  - The first argument to the operator is a column which has a domain index defined on it.

  - The indextype of the domain index (specified in `ODCIIndexInfo` parameter) supports the current operator.

  - All other arguments to the operator are value arguments (literals) which are passed in through the `<valargs>` parameters.

- The `ODCIIndexStart` method should initialize the index scan as needed (using the operator-related information in the `pi` argument) and prepare for the subsequent invocations of `ODCIIndexFetch`.

- The `strt`, `stop` parameters together with the `bndflg` value in `ODCIPredInfo` parameter specify the range of values within which the operator return value should lie.

- Bounds for operator return values are specified as follows:

  - If the predicate to be evaluated is of the form `op` `LIKE` `val`, the `ODCIIndexPrefixMatch` flag is set. In this case, the start key contains the value `<val>` and the stop key value is irrelevant.

  - If the predicate to be evaluated is of the form `op` = `val`, the `ODCIIndexExactMatch` flag is set. In this case, the start key contains the value `<val>` and the stop key value is irrelevant.

  - If the predicate to be evaluated is of the form `op` > `val`, `startkey` contains the value `<val>` and stop key value is set to `NULL`. If the predicate is of the form `op` >= `<val>`, the flag `ODCIIndexIncludeStart` is also set.

  - If the predicate to be evaluated is of the form `op` `< val`, stop key contains the value <val> and the start key value is set to `NULL`. If the predicate is of the form `op` `<= val`, the flag `ODCIIndexIncludeStop` is also set.

- A context value can be returned to Oracle (through the `SELF` argument) which will then be passed back to the next query-time call. The next call will be to `ODCIIndexFetch` if the evaluation continues, or to `ODCIIndexStart` if the evaluation is restarted. The context value can be used to store the entire evaluation state or just a handle to the memory containing the state.

- If the same indextype supports multiple operators with different signatures, multiple `ODCIIndexStart` methods need to be implemented, one for each distinct combination of value argument datatypes. For example, if an indextype supports three operators:

  1. `op1(number, number)`

  2. `op1(varchar2, varchar2)`

  3. `op2(number, number)`

  two `ODCIIndexStart` routines would need to be implemented:

  - `ODCIIndexStart(...., NUMBER)`— handles cases (1) and (3) which has a `NUMBER` value argumen`t`

  - `ODCIIndexStart(...., VARCHAR2)`— handles case (2) which has a `VARCHAR2` value argument

- The query information in `qi` parameter can be used to optimize the domain index scan, if possible. The query information includes hints that have been specified for the query and the list of relevant ancillary operators referenced in the query block.

### ODCIIndexTruncate()

Invoked when a `TRUNCATE` statement is issued against a table that has a domain index defined on one of its columns.

Syntax

    ODCIIndexTruncate(
       ia ODCIIndexInfo,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the indexed column
    env
| The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error, or `ODCIConst.Warning`.

While truncating a local domain index, the first N+1 calls can return `ODCIConst.ErrContinue` too.

Usage Notes

- This function should be implemented as a static type method.

- After this function executes, the domain index should be empty (corresponding to the empty base table).

- While the `ODCIIndexTruncate` routine is being executed, the domain index is marked `LOADING`. If the `ODCIIndexTruncate` routine returns with an `ODCIConst`.`Error` (or exception), the domain index will be marked `FAILED`. The only operation permitted on `FAILED` domain indexes is `DROP` `INDEX`, `TRUNCATE` `TABLE` or `ALTER` `INDEX` `REBUILD`. If `ODCIIndexTruncate` returns with `ODCIConst`.`Warning`, the operation succeeds but a warning message is returned to the user.

- Every SQL statement executed by `ODCIIndexTruncate` is treated as an independent operation. The changes made by `ODCIIndexTruncate` are not guaranteed to be atomic.

- This method is invoked for truncating a non-partitioned index, truncating a local domain index, and also for truncating a single index partition during `ALTER TABLE TRUNCATE PARTITION`.

  For truncating a non-partitioned index, the `ODCIIndexTruncateis` invoked once, with the `IndexPartition`, `TablePartition` and `callProperty` set to `NULL`.

  For truncating a local domain index, the routine is invoked N+2 times, where N is the number of partitions.

  For truncating a single index partition during `ALTER TABLE TRUNCATE PARTITION`, this routine is invoked once with the `IndexPartition` and the `TablePartition` filled in and the `callProperty` set to `NULL`.

### ODCIIndexUpdate()

Invoked when a row is updated in a table and the updated column has a domain index defined on it.

Syntax

    ODCIIndexUpdate(
       ia ODCIIndexInfo,
       rid VARCHAR2,
       oldval <icoltype>,
       newval <icoltype>,
       env ODCIEnv) RETURN NUMBER;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the index and the indexed column
    rid
|  | The row identifier of the updated row
    oldval
|  | The value of the indexed column before the update. The datatype is the same as that of the indexed column.
    newval
| The value of the indexed column after the update. The datatype is the same as that of the indexed column.
    env
|  | The environment handle passed to the routine

Returns

`ODCIConst.Success` on success, or `ODCIConst.Error` on error

Usage Notes

- The function should be implemented as a static type method.

- This method should update the tables or files storing the index data for the updated row.

- In addition to a SQL `UPDATE` statement, a LOB value can be updated through a variety of `WRITE` interfaces (see Oracle Database Application Developer's Guide - Large Objects). If a domain index is defined on a `LOB` column or an object type containing a `LOB` attribute, the `ODCIIndexUpdate` routine is called when a LOB locator is implicitly or explicitly closed after one or more write operations.

- If `ODCIIndexUpdate` is invoked at the partition level, then the index partition name is filled in the `ODCIIndexInfo` argument.

### ODCIIndexUtilCleanup()

Implemented only if you want to have transportable tablespace support for domain indexes defined using this indextype. It is invoked during a transportable tablespace session to cleanup any temporary state created by `ODCIIndexUtilGetTableNames`.

Syntax

    ODCIIndexUtilCleanup (
       context  PLS_INTEGER);

Parameter | IN/OUT | Description
--- | --- | ---
    context
| The number created by `ODCIIndexGetTableNames` that uniquely identifies state information for a particular index.

Usage Notes

- The procedure should be implemented as a static type method.

- `ODCIIndexUtilCleanup` deletes any temporary state associated with the parameter context.

- Exceptions raised by `ODCIIndexUtilCleanup` will be ignored by its caller.

### ODCIIndexUtilGetTableNames()

This method needs to be implemented only if you want to have transportable tablespace support for domain indexes defined using this indextype. It is invoked during a transportable tablespace session to determine if the secondary tables storing the index data should be transported.

Syntax

    ODCIIndexUtilGetTableNames(
       ia sys.odciindexinfo,
       read_only PLS_INTEGER,
       version varchar2,
       context OUT PLS_INTEGER) RETURN BOOLEAN;

Parameter | IN/OUT | Description
--- | --- | ---
    ia
| Contains information about the index and the indexed column
    read_only
| Specify 1 if the encompassing transaction is read-only, meaning no writes allowed. Otherwise 0.
    version
|  | Version of export making the call.
    context
|  | A unique number that is used by `ODCIIndexUtilCleanup` to facilitate the clean up of any state held open between `ODCIIndexUtilGetTableNames` and `ODCIIndexCleanup`.

Returns

TRUE if the domain indexes' secondary tables should be transported. Otherwise, the function returns FALSE.

Usage Notes

- This function should be implemented as a static type method.

- This function should return TRUE or FALSE based on whether the secondary tables should be transported or not. Secondary objects other than tables do not participate in transportable tablespaces. They will need to be recreated on the import side when the `ODCIIndexCreate` method is invoked with the `ODCI_INDEX_TRANS_TBLSPC` bit set in the `ODCIIndexInfo.IndexInfoFlags`.